/* LoadingWidget.js
 *
 * Copyright 2006, Tim Dwelle.
 *
 * Licensed under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in
 * compliance with the License.  You may obtain a copy of
 * the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 * CONDITIONS OF ANY KIND, either express or implied.  See
 * the License for the specific language governing
 * permissions and limitations under the License.
 *
 */

$package("dowry.widget");

/**
 * LoadingWidget provides support for a loading message or
 * graphic to be shown when making a remote call to the
 * server.
 *
 * <p>
 * This widget should be applied to a block element (like
 * a <code>&lt;div&gt;</code>) that is appropriately styled
 * for your desired loading message.  For instance, the
 * following CSS declaration places an animating loading
 * message in the upper right hand corner of the page.
 * </p>
 *
 * <pre>
 * .loader
 * {
 *    background-image : url(ajax-loader.gif);
 *    position         : absolute;
 *    top              : 0px;
 *    right            : 0px;
 *    height           : 32px;
 *    width            : 32px;
 * }
 * </pre>
 *
 * <p>
 * Some good animating loading images can be found at:
 * </p>
 *
 * <ul>
 *  <li>
 *   <a href="http://www.napyfab.com/ajax-indicators/">
 *        http://www.napyfab.com/ajax-indicators/
 *   </a>
 *  </li>
 *  <li>
 *   <a href="http://www.ajaxload.info/">
 *        http://www.ajaxload.info/
 *   </a>
 *  </li>
 * </ul>
 *
 */
$class("LoadingWidget").$extends("Widget").$as(
{
    /**
     * Internal count. Don't want to stop showing until
     * all the <code>show()</code>s have had a corresponding
     * <code>hide()</code>.
     *
     */
    _count : 0,

    /**
     * When the loading widget is started, hide the current
     * loading message (it may or may not be currently
     * displayed), and then register it with the DWR
     * engine's pre and post hooks.
     *
     */
    start : function()
    {
        // we wait to hide until start, so
        // that we may get a chance to see
        // the contents of the loading div
        // while Dowry is initializing
        this.hide(true);

        if (window.DWREngine)
        {
            DWREngine.setPreHook(this.show);
            DWREngine.setPostHook(this.hide);
        }
    },

    /**
     * Hides the widget's element by styling it to
     * display <code>none</code> if there are no pending
     * loads still outstanding; otherwise, it just
     * decrements the count of pending loads so it is
     * one step closer to hidden.  If you want to force
     * the loading message to hide, regardless of any
     * pending loads, simply pass in the the <code>
     * force</code> flag.
     *
     * @param force  (optional) boolean indicating to force
     *               the hiding of the loading message,
     *               regardless of any pending loads
     *
     */
    hide : function(force)
    {
        this._count--;

        var ele = this.getElement();
        if (ele && (force || this._count < 1))
        {
            ele.style.display = "none";
            this._count = 0;
        }
    },

    /**
     * Shows the widget's element by styling it to
     * display <cpde>block</code>.
     *
     */
    show : function()
    {
        var ele = this.getElement();
        if (ele)
        {
            ele.style.display = "block";
            this._count++;
        }
    }
});